home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
USA Bestseller
/
USA BESTSELLER Vol 1-95 (Hepp-Computer)(1995).iso
/
e058
/
hyperdoc.hpr
< prev
next >
Wrap
Text File
|
1994-04-05
|
26KB
|
557 lines
.SubTopic Entry
\B HYPERDOC v1.51
HyperDoc is a utility for producing and distributing hypertext
documents, alone or with your applications. Documents can be help
files, user manuals, or any other type of complex information
requiring frequent intra-document references. Hyperlinks allow
the user to quickly jump from one section of the document to any
other section, by simply selecting a highlighted topic. HyperDoc
also allows subsections - with a top and a bottom - that behave as
separate documents to the user.
The button bar at the top of the screen is fully configurable to
your specific application, allowing you to offer hyperlinks that
are always available regardless of where the user is in the docu-
ment. For example, the <Contents> button is provided so you can
access that section at any time.
~Table of Contents~_Contents~
.EndSubTopic
.SubTopic _Contents
\B Table of Contents
─────────────────────────────────────┬─────────────────────────────────────
│
Overview; │
~Hypertext~Hypertext~ │
│ HyperDoc
Documents; │
~Planning~Planning~ │ Using and distributing HyperDoc
~Creating~Creating~ │ with your programs will make it
~Compiling~Compiling~ │ much easier for users to learn
~Distributing~Distributing~ │ how your product works, and will
~User Considerations~Usage~ │ substantially enhance your image
~Button Bar~ButtonBar~ │ as a company that cares about
~Command Line Options~Switches~ │ quality and ease of use.
~Command Summary~CmdSum~ │
│ For more information, choose
Licensing; │ ~Distribution Details~Distributing~.
~Registration~Registration~ │
│
│
│
─────────────────────────────────────┴─────────────────────────────────────
.EndSubTopic
.SubTopic Hypertext
\B Hypertext
───────────────────────────────────────────────────────────────────────────
Hypertext is a technique that uses hyperlinks to connect
different sections of a document in such a way that the user can
jump from one section to another without regard to the actual
location of the text within the document. Additionally, unlike
printed documents, hypertext allows one to move from place to
place without having to worry about how to get back. Every jump
from each section is recorded and can be played back in reverse at
any point.
.EndSubTopic
.SubTopic Planning
\B Planning Documents
───────────────────────────────────────────────────────────────────────────
A good plan will help you to make the most of what HyperDoc has
to offer.
Ask yourself the following questions;
■ Will my document need to be broken up into sections? If yes,
take a look at the section on ~SubTopics~SubTopics~.
■ How will the button bar be configured? If an index is in the
plan, you might want to allow users to get at it from
anywhere in the document - use the ~Button Bar~ButtonBar~ for this.
■ How will you or your users invoke HyperDoc? If you will be
shelling from another program, consider ~Memory~MemInfo~ limitations,
~Command Line~Switches~ parameter settings, etc.
There are of course, many more things to consider. In time, you
will become skilled at creating documents ideally suited for your
applications.
.EndSubTopic
.SubTopic Creating
\B Creating Documents
───────────────────────────────────────────────────────────────────────────
Once you have a good idea of how your document will be
structured, the next step is to simply enter the text of the
document. Except for keeping each section of text separated, do
not be concerned with embedded codes until all text has been
entered. This is suggested because the embedded codes take a
certain amount of space on each line, making the text appear as
though it is not aligned properly until it is viewed. The easiest
way to add hyperlinks and other embedded codes to your document,
is to wait until it is completely finished, then use your editor
to implement a search & replace for the desired references. For
example, you may want to replace every occurance (or just selected
\L occurances) of "Appendix" with "~Appendix~Appendix~" to offer the
reader of your document instant access to the subtopic Appendix
when it is referenced.
Let's look at the simplest type of document, just plain ASCII
text without any embedded codes;
"This document has no hyperlinks and requires that
the user manually navigate from line to line and
section to section within the text. If there were
several hundred pages worth of information, this
technique could become quite frustrating,
especially if there are many references to other
sections - such as an index."
Now, add some embedded codes to make it easier to get around;
"This document has hyperlinks that allow the user
to jump from section to section within the text.
If there were several hundred pages worth of
information, this technique could become quite
valuable, especially if there are many references
to other sections - such as an ~index~SampleIndex~."
\B ┌─────────────────────┴─────┘
\B └─── Embedded code looks like: ~index~SampleIndex~
\B ├───┘ ├─────────┘│
\B Text inside button (can be anything) ─┘ │ │
\B │ │
\B Hyperlink destination (matches a SubTopic or Label) ──┘ │
\B │
\B Delimiter (3rd of 3) ──────────┘
.Label SubTopics
\B SubTopics
If you plan to break up the document into two or more individual
sections, then you need to be aware of how to create these
divisions between topics. In HyperDoc, each separate section is
called a SubTopic. Subtopics have a beginning and an ending.
To start a subtopic, place this embedded command on the line
directly above where this section is to begin;
\B.SubTopic TitleName
│ │
│ └─── TitleName is any name you wish to give this section
│ up to 20 characters (more is allowed, but only the
│ first 20 count). Names are not case sensitive.
│
└─── Note that command MUST start in column 1.
\B "This is the text within this subtopic. It is only
\B accessible by selecting a hyperlink that
\B references the subtopic TitleName."
To end a subtopic, place the following command on the line below
the last line of the section;
┌─── Note that command MUST start in column 1.
│
\B.EndSubTopic
.EndSubTopic
.SubTopic SampleIndex
\B Sample Index
─────────────────────────────────────────────────────────────────────────────
This might one or more pages of index references that the user
can easily look at, hyperlink to another section or return to the
last place they were at before jumping to the index. Select
<BACK> to return.
.EndSubTopic
.SubTopic Distributing
\B Distributing Documents
───────────────────────────────────────────────────────────────────────────
When you register HyperDoc, you are allowed to distribute
unlimited copies of each document that you compile with the
HyperDoc compiler. Also, you may distribute one copy of the viewer
HYPERDOC.EXE with each document and without royality. You may not
distribute the compiler program, HYPERC.EXE or transfer your
rights granted by the ~License Agreement~Agreement~.
There are several things you will want to consider if you intend
to distribute your documents. Choose ~User Considerations~Usage~ for
more information. Also see ~Registration~Registration~ for details on getting a
registered copy of HyperDoc.
Compiled documents consist of the text file <docname.HPR>, the
pointer file <docname.PTR> and the index file <docname.NDX>.
Be sure to include all of these files if you decide to register
HyperDoc and distribute documents that you have compiled.
.EndSubTopic
.SubTopic Agreement
\B License Agreement
───────────────────────────────────────────────────────────────────────────
Once registered, you (LICENSEE), may use the HyperDoc runtime
program (RUNTIME PROGRAM) and the HyperDoc compiler (COMPILER)
subject to the following terms:
LICENSEE may compile and distribute any number documents compiled
with the COMPILER. LICENSEE may also distribute royalty free,
one copy of the RUNTIME PROGRAM along with each copy of documents
compiled with COMPILER so the recipient may view the documents.
LICENSEE may install and use the COMPILER on one machine only,
and must pay for network use if it is to be used on a network,
regardless of whether or not other people will be using the
program. LICENSEE agrees to be fully liable to Borgaard & Co. for
losses due to the intentional or unintentional distribution of the
COMPILER included with your registered copy of HyperDoc. The
COMPILER and every document created with it are serialized and
traceable to the registered licensee.
LICENSEE MAY NOT compile documents for others and allow such
documents to be distributed, with or without the RUNTIME PROGRAM.
Such activity would constitute a transference of this license
agreement, which is not allowed by the terms herein.
LICENSEE may not sell, transfer, or assign any of the rights
granted by this agreement without the express written permission
of Borgaard & Co., P.O. Box 7843 Bend, OR 97708-7843.
.EndSubTopic
.SubTopic Registration
\B Hyperdoc Registration
───────────────────────────────────────────────────────────────────────────
This UNREGISTERED copy of HyperDoc contains a compiler that
places certain limitations on the size of documents it will allow
among other things, and the runtime program will display the "Not
registered" message before allowing you to view a document.
You MAY NOT distribute any document created with this UNREGISTERED
compiler.
Registration will allow you to distribute both documents and the
HyperDoc runtime program, royalty free and without any limitations
on the number of documents you distribute. Use and distribution is
subject to the terms of the ~License Agreement~Agreement~.
To receive a registered copy of HyperDoc, send $39 plus $3.50
shipping & handling along with the ~Order Form~OrderForm~ payable to:
\B J Borgaard & Co.
\B P.O. Box 7843, Bend OR 97708-7843
.EndSubTopic
.SubTopic OrderForm
\B ORDER FORM
Choose <PRINT> from the button bar to print this order form or
include the requested information with your order:
_______________________________________________________________
LAST NAME FIRST NAME INITIAL
_______________________________________________________________
STREET ADDRESS (NO P.O. BOX DELIVERIES)
_______________________________________________________________
CITY STATE ZIPCODE AREA CODE +PHONE
\B The above information is required. Orders will not be processed
\B without complete information.
HyperDoc single-user copies @ $39 each ............ ___________
HyperDoc multi-user copies @ $59 each ............. ___________
(Multi-user version suitable for use on most any
DOS based network software - number of nodes
is not limited)
Shipping & handling @ $3.50 per order plus $1.00
each for additional copies ordered. ............... ___________
TOTAL ............................................. ___________
\B Make checks payable and send to:
\B J Borgaard & Co.
\B P.O. Box 7843, Bend OR 97708-7843
.EndSubTopic
.SubTopic Compiling
\B Compiling Documents
───────────────────────────────────────────────────────────────────────────
Documents are compiled with HYPERC.EXE, the HyperDoc compiler.
This step MUST be performed before a document can be viewable with
HYPERDOC.EXE. Compiling creates the index file <docname.NDX> and
the line pointer file <docname.PTR>. Both of these files are used
to assist the HyperDoc viewer in locating sections of text within
a document.
To compile a finished document, type HYPERC <docname>. You do
not need to include the file extension if your document extension
is <.HPR>. If your document has errors, they will be reported at
this time. You will most likely encounter some errors during the
initial stages of document preparation. It's easy to misspell a
label. Labels are not case sensitive - "LABELNAME" is the same as
"labelname".
Some of the errors you may encounter are;
■ Expected - .EndSubTopic before .SubTopic - If you use
subtopics to break up your document, every .SubTopic must be
followed at some point by a .EndSubTopic command.
■ Unresolved references - when you reference a label in your
document, and the compiler fails to find that label, you will
see this error, combined with the label that could not be
found. The viewer program will simply do nothing when the user
selects a hyperlink to a reference that is unresolved.
■ Syntax errors - If you forget to use the correct formatting
in your hyperlinks, it will be detected. The correct format
for a hyperlink reference is;
\B ~Button text~LabelName~
■ Label name too long - If a label exceeds twenty characters
in length, HyperDoc will ignore the extra characters beyond
twenty. This is not really an error, but more of a warning to
you that if you rely on two labels that are the same except
for characters twenty-one and beyond, HyperDoc will choose
only one of the labels and ignore the other.
.EndSubTopic
.SubTopic ButtonBar
\B Configuring the Button Bar
───────────────────────────────────────────────────────────────────────────
To make a subtopic available on the button bar at the top of the
screen, simply precede the subtopic or label name with the
underscore character "_". To create an index for your document
that is available on the button bar, the subtopic might look like
this;
\B.SubTopic _Index
\B - A -
\B ~Alphabet soup recipes~AlphaSoup~
\B ~Alpha-numerical soup recipes~AlphaNumSoup~
\B - B -
\B and so on..
\B.Label _Appendix A
\B Appendix A text..
\B.EndSubTopic
You may have as many items in the button bar as will fit in the
space provided. If you have more subtopics and/or labels than
will fit in the space provided, the additional topics or labels
will be ignored, but still can be referenced by hyperlink
references within your document.
.EndSubTopic
.SubTopic Usage
\B Usage Considerations
───────────────────────────────────────────────────────────────────────────
When using the HyperDoc viewer, the user may or not be using a
mouse or trackball device. If you offer instruction to users
within your document on how to navigate (if you think such advice
would be needed) then this fact should be kept in mind when
creating the language of your instructions.
Many people use amber, green or paper-white monitors instead of
color - HyperDoc will simply replace the green accents with a
highlight attribute on the non-color monitor.
If you are distributing your documents along with a program, and
that program invokes the HyperDoc viewer in a shell, be sure to
check to see that enough memory is available to execute HyperDoc.
HyperDoc requires a minimum of 124K to load. For more information,
choose ~Memory Requirements~MemInfo~.
.EndSubTopic
.SubTopic Switches
\B Command Line Switches - HyperDoc View Utility
───────────────────────────────────────────────────────────────────────────
The HyperDoc viewer may be invoked with several optional
parameters. By default, HyperDoc will seek a .HPR file that has
the same base name as the HyperDoc viewer program. This allows
you to rename HYPERDOC.EXE to some other more appropriate name
such as MANUAL.EXE or HELP.EXE, in which case HyperDoc will
attempt to load a file with the name MANUAL.HPR or HELP.HPR.
This document auto- seeking feature requires OS compatibility
with DOS 3.0 or greater.
If the default document file is not available, and no other
document is specified, HyperDoc will terminate with a "File must
be specified" error.
Explanation of command line parameters:
[Parm] - denotes optional parameter
<Parm> - denotes required parameter
NOTE: Do not enter brackets - [], <>.
HYPERDOC [<filename>[.HPR]] [/M] [/P:<Dev/File>] [/L:<Label>]
where:
<filename> = Document file for viewing other than the
default file. If no extension is provided,
an extension of .HPR is assumed. Default is
<ProgName.HPR> where ProgName is the name
of the HyperDoc viewer program, which is
HYPERDOC.EXE as shipped.
/M = Tells HyperDoc to not use color attributes
when displaying text. HyperDoc will
automatically detect the type of monitor
in use, but there may be some instances
when you will want this option, so it has
been provided.
/P: = Informs HyperDoc of which device to use
when the user selects < Print> from the
button bar. The device can be a filename
or port designation such as LPT1, COM1,
or OUTFILE.TXT. Default is LPT1.
/L: = Tells HyperDoc to begin at some label
other than Entry. This feature is most
useful for applications where a program
needs to provide context- sensitive help.
By shelling to HyperDoc with the /L:Label
parameter, the section titled Label will
be the opening screen. Default is Entry.
If the specified label is not found, the
default label Entry is used. If Entry is
not found, HyperDoc will start at the
second line in the file.
example:
\B HYPERDOC MYFILE /M /P:LPT2 /L:FuncKeys ── Starts HyperDoc at
\B └──┬─┘ │ └──┬──┘ FuncKeys SubTopic
\B View MYFILE.HPR ───┘ │ │
\B │ └── Use printer on LPT2.
\B │
\B └──────── Do not use color.
.EndSubTopic
.SubTopic MemInfo
\B Memory Requirements - HyperDoc View Utility
───────────────────────────────────────────────────────────────────────────
The HyperDoc view utility requires a minimum of 130KB RAM for
loading, and more may be required for future releases, as
features are added. Every effort is made to keep memory
requirements as low as possible during the on-going development
effort.
.EndSubTopic
.SubTopic CmdSum
\B Document Command Summary
───────────────────────────────────────────────────────────────────────────
Explanation of embedded document commands:
[Parm] - denotes optional parameter
<Parm> - denotes required parameter
NOTE 1: Do not enter brackets - [], <>.
NOTE 2: ALL commands preceded by a dot "." or a backslash
"\" MUST be placed at the left-most column (column 1).
.SubTopic <Label> - Indicates the start of a subsection that
will be treated as a seperate document
as far as the user will be concerned. The
user will not be able to scroll up beyond
this line and will need to execute a
hyperlink to another section to move outside
this boundry.
.EndSubTopic - Indicates the end of a subsection that will
be treated as a seperate document as far as
the user will be concerned. The user will
not be able to scroll down beyond this line
and will need to execute a hyperlink such as
<BACK> or a reference to another section to
move outside this boundry.
.Label <Label> - Establishes a point in the document that
may be referenced just like a .SubTopic,
except that it presents no boundries and
therefore may be scrolled past in both
directions.
\B - Causes HyperDoc to display this line in
the bold attribute. Bold lines may not have
other embedded commands.
\L - Causes HyperDoc to display this line without
regard to any embedded commands that may be
present. The line is displayed as-is.
\L ~Button~Label~ - Creates a delimited reference within the
document that points to another line
elsewhere. When selected by the user, whether
by using the mouse button or the [Enter] key,
will cause HyperDoc to jump to that location
in the document identified as <Label>.
\L For example, the command: ~This Button~There~
will display the text <This Button>, and if
selected, will jump to a point in the document
labeled as;
.SubTopic There
or;
.Label There
.EndSubTopic
